package com.googlecode.nls4j;

import java.util.Locale;

/**
 * BundleLoaders are used to load resources of type <b>V</b> which identified by
 * {@link NlsKey}s of type <b>K</b> and collect the loaded resources into
 * {@link NlsBundle}s.
 * 
 * @author Andrey Pavlenko
 */
public interface BundleLoader<K extends NlsKey<V>, V> {

    /**
     * Loads {@link NlsBundle} for the specified key type and locale.
     * 
     * @param keyType
     *            type of {@link NlsKey}s identifying resources in the bundle.
     * @param locale
     *            {@link Locale} for which the bundle must be loaded.
     * @return A loaded bundle or null if the bundle can not be loaded.
     * @throws IllegalArgumentException
     *             if the key type is not supported by this bundle loader.
     * @throws NullPointerException
     *             if either keyType or locale argument is null.
     */
    public NlsBundle<K, V> loadBundle(Class<K> keyType, Locale locale)
            throws IllegalArgumentException, NullPointerException;

    /**
     * Returns the {@link NlsBundle} containing default values (the values
     * provided by the {@link NlsKey#getDefaultValue(Locale)} method) for the
     * specified key type and locale. This method is usually used if it was
     * unable to load a bundle using the {@link #loadBundle(Class, Locale)}
     * method. This method must never return null.
     * 
     * @param keyType
     *            type of {@link NlsKey}s identifying resources in the bundle.
     * @param locale
     *            {@link Locale} for which the bundle must be created.
     * @return The default values bundle.
     * @throws IllegalArgumentException
     *             if the key type is not supported by this bundle loader.
     * @throws NullPointerException
     *             if either keyType or locale argument is null.
     */
    public NlsBundle<K, V> getDefaultBundle(final Class<K> keyType,
            final Locale locale) throws IllegalArgumentException,
            NullPointerException;
}
